Skip to content

Update AppView.php#1050

Closed
dereuromark wants to merge 1 commit into5.xfrom
dereuromark-patch-1
Closed

Update AppView.php#1050
dereuromark wants to merge 1 commit into5.xfrom
dereuromark-patch-1

Conversation

@dereuromark
Copy link
Copy Markdown
Member

@link should be used for linking things together. Here, a simple @see is correct IMO.

Refs https://github.com/dereuromark/cakephp-ide-helper/blob/b6237cc03a50735bd43a5290e0a9e77972864208/config/app.example.php#L34

`@link` should be used for linking things together.
Here, a simple `@see` is correct IMO.

Refs https://github.com/dereuromark/cakephp-ide-helper/blob/b6237cc03a50735bd43a5290e0a9e77972864208/config/app.example.php#L34
@dereuromark dereuromark added this to the 5.x milestone Jul 22, 2025
@LordSimal
Copy link
Copy Markdown
Contributor

@see can be a URL or a FQSEN https://docs.phpdoc.org/guide/references/phpdoc/tags/see.html
@link must be a URL https://docs.phpdoc.org/guide/references/phpdoc/tags/link.html

So in this case @link is fine imho since its more specific.

@dereuromark
Copy link
Copy Markdown
Member Author

dereuromark commented Jul 22, 2025

No, the semantic meaning is different, and also link can and should be used for linking things together IMO.
See referenced PR/changes.

@link would mess with the annotator since using link over uses (since uses is used by phpunit for coverage unfortunately).

See should be enough here, the fact that it can be FQCN and referencing internal files and methods does not disqualify its semantic use here.

@dereuromark
Copy link
Copy Markdown
Member Author

Also
https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.see.pkg.html

"Display a link to the documentation for an element"

The @see tag may be used to document any element (global variable, include, page, class, function, define, method, variable)

IMO exactly what we want in these cases

@ADmad
Copy link
Copy Markdown
Member

ADmad commented Jul 22, 2025

No, the semantic meaning is different, and also link can and should be used for linking things together IMO.

Which documentation says that?

This is what is says for @link from the docs you linked https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.link.pkg.html

Display a hyperlink to a URL in the documentation
The guidelines for giving the element name to @link are the same as outlined in the @see manual page.

So I don't see anything wrong with the current @link here.

Phpunit may have hijacked this tag for it's own use. Also usage of phpdoc annotations is now deprecated in phpunit and it uses PHP attributes instead.

@dereuromark
Copy link
Copy Markdown
Member Author

dereuromark commented Jul 22, 2025

Well, the IDEHelper now has to use @link either way for linking code and test code - see the linked reasons above.
So I would prefer if we used the @see tag for normal doc linking which is reasonable enough IMO.

@dereuromark
Copy link
Copy Markdown
Member Author

I can add dereuromark/cakephp-ide-helper#392 for now, but would prefer if we used a consistent and helpful tag here, so that @link in IDE actually is able to also show the linked parts of the system.

@dereuromark
Copy link
Copy Markdown
Member Author

dereuromark commented Jul 22, 2025

The core seems to also use both randomly.
I would prefer if we consolidated this to prefer link for linking:

@link \Cake\Core\ObjectRegistry::unload()

and for doc links:

@see http....

also in core code.
I can make a PR here for either direction.

@dereuromark dereuromark deleted the dereuromark-patch-1 branch August 21, 2025 13:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants